home *** CD-ROM | disk | FTP | other *** search
/ AmigActive 24 / AACD 24.iso / AACD / Programming / gcc-2.95.3-3 / info / gcc-amigaos.info < prev    next >
Encoding:
GNU Info File  |  2001-07-15  |  40.7 KB  |  1,148 lines
  1. This is Info file gcc-amigaos.info, produced by Makeinfo version 1.68
  2. from the input file ./gcc-amigaos.texi.
  3.  
  4.    This document describes implemenation specific features of the GNU CC
  5. compiler port for the AmigaOS.
  6.  
  7.    Copyright (C) 1996, 1997 Kamil Iskra
  8.  
  9.    Permission is granted to make and distribute verbatim copies of this
  10. manual provided the copyright notice and this permission notice are
  11. preserved on all copies.
  12.  
  13. 
  14. File: gcc-amigaos.info,  Node: Top,  Next: Introduction,  Prev: (dir),  Up: (dir)
  15.  
  16.    This document describes the AmigaOS-only features of the `GNU CC'
  17. compiler.
  18.  
  19.    Last updated Oct 25th, 1997.
  20.  
  21. * Menu:
  22.  
  23. * Introduction::  Purpose of this document.
  24.  
  25. * Invocation::    Command line options.
  26. * Attributes::    Variable and function attributes.
  27. * Defines::       Preprocessor symbols.
  28. * Miscellaneous:: Uncategorizable.
  29.  
  30. * Index::         Concept index.
  31.  
  32. 
  33. File: gcc-amigaos.info,  Node: Introduction,  Next: Invocation,  Prev: Top,  Up: Top
  34.  
  35. Introduction
  36. ************
  37.  
  38.    This document is supposed to be an addendum to the baseline `GCC'
  39. documentation.
  40.  
  41.    It focuses on the features that are visible by users and are
  42. important to them. It is not supposed to document the internals of the
  43. AmigaOS port of `GCC'.
  44.  
  45.    It describes features implemented in the `Geek Gadgets GCC' port.
  46. As of this writing, this is version 2.7.2.1, `Geek Gadgets' snapshot
  47. `970728'. For more information about `Geek Gadgets', please refer to:
  48.  
  49. http://www.ninemoons.com/ADE/ADE.html
  50. ftp://ftp.ninemoons.com/pub/geekgadgets/README
  51.  
  52.    This document also describes some features that are not yet part of
  53. the `Geek Gadgets GCC' port, but which should be there soon. Such
  54. features are marked with *[EXPERIMENTAL]*. If you have `GCC' from a
  55. snapshot later than specified above, it's possible that these features
  56. are available in it. Some of these features might also be available in
  57. BETA `GCC' releases available on Kamil Iskra's WWW page:
  58.  
  59. http://student.uci.agh.edu.pl/~iskra/ade.html
  60.  
  61.    This document focuses on `GCC'. It does not describe the
  62. AmigaOS-only features of other `GNU' packages, such as `binutils',
  63. unless they are very closely connected to `GCC'.
  64.  
  65.    This means, that, unless stated otherwise, when we talk about the
  66. "compiler", we mean the `gcc', `cpp' and `cc1' executables, i.e., the
  67. executables that convert `C' source code to assembly source code. The
  68. assembler and linker are generally beyond the scope of this document.
  69.  
  70.    The primary source of information used to create this document was
  71. the `GCC' source code. Some parts of this document are based on:
  72.  
  73.    * The `LibNIX' manual, written by Matthias Fleischer and Gunther
  74.      Nikl:
  75.  
  76.      fleischr@izfm.uni-stuttgart.de
  77.      gnikl@informatik.uni-rostock.de
  78.  
  79.    * The `A2IXLibrary' manual, written by Hans Verkuil:
  80.  
  81.      hans@wyst.hobby.nl
  82.  
  83.    * The `README' file, maintained by Rask Ingemann Lambertsen:
  84.  
  85.      gc948374@gbar.dtu.dk
  86.      http://www.gbar.dtu.dk/~c948374/GNU/
  87.  
  88.    * The `Geek Gadgets FAQ', maintained by Lynn Winebarger:
  89.  
  90.      owinebar@indiana.edu
  91.      http://nickel.ucs.indiana.edu/~owinebar/interests/amiga/amiga.html
  92.  
  93.    * The `FAQ for g++ and libg++', written by Joe Buck:
  94.  
  95.      jbuck@synopsys.com
  96.      http://www.cygnus.com/misc/g++FAQ_toc.html
  97.  
  98.    * Discussions on various `Geek Gadgets' mailing lists:
  99.  
  100.      gg@ninemoons.com
  101.      gg-gcc@ninemoons.com
  102.      gg-ixemul@ninemoons.com
  103.  
  104.    This document was created by Kamil Iskra. Please email any questions,
  105. suggestions etc. to <iskra@student.uci.agh.edu.pl> or, even better, to
  106. the <gg-gcc@ninemoons.com> mailing list.
  107.  
  108.    The author would like to thank Kriton Kyrimis <kyrimis@cti.gr> and
  109. Lars Hecking <lhecking@nmrc.ucc.ie> for correcting an awful lot of
  110. language mistakes in this document.
  111.  
  112. 
  113. File: gcc-amigaos.info,  Node: Invocation,  Next: Attributes,  Prev: Introduction,  Up: Top
  114.  
  115. Invocation
  116. **********
  117.  
  118.    The AmigaOS port of `GCC' supports the following non-standard
  119. command line options:
  120.  
  121. * Menu:
  122.  
  123. * -noixemul::           Link with `LibNIX'.
  124.  
  125. * -fbaserel::           Produce `a4'-relative data.
  126. * -resident::           Produce a `pure' executable.
  127. * -fbaserel32::         Produce `a4'-relative data with no size limits.
  128. * -resident32::         Produce a `pure' executable with no size limits.
  129. * -msmall-code::        Produce `PC'-relative code.
  130.  
  131. * -mstackcheck::        Produce stack-checking code.
  132. * -mstackextend::       Produce stack-extending code.
  133. * -mfixedstack::        Produce plain code.
  134.  
  135. * -mrestore-a4::        Reload `a4' in public functions.
  136. * -malways-restore-a4:: Reload `a4' in all functions.
  137.  
  138. * -mregparm::           Pass function arguments in registers.
  139.  
  140. * -frepo::              Enable `C++' Template Repository.
  141.  
  142.    Accordingly, the AmigaOS port of `GCC' supports several flavors of
  143. linker libraries. *Note Relation between library flavors and
  144. compile-time options: Library flavors.
  145.  
  146. 
  147. File: gcc-amigaos.info,  Node: -noixemul,  Next: -fbaserel,  Prev: Invocation,  Up: Invocation
  148.  
  149. -noixemul
  150. =========
  151.  
  152.    By default, the executables created with `GCC' require
  153. `ixemul.library' to run. This has its advantages (easy porting of
  154. `UN*X' programs, resource tracking, debugging, profiling, etc) and
  155. disadvantages (`UN*X'-style pathnames, large shared library, etc).
  156.  
  157.    If `-noixemul' is specified on the `GCC' command line, the
  158. executable created will not require `ixemul.library' -- it will use the
  159. static linker library `LibNIX' instead. This library is very Amiga-like
  160. and `SAS/C'-like, so it is convenient for the AmigaOS-specific
  161. development.
  162.  
  163.      *Note*: There is no great mystery about the `-noixemul' option. It
  164.      has absolutely no effect on the code generated by the compiler,
  165.      only instructing the `gcc' driver to pass different options to the
  166.      linker and preprocessor (*note Options information::., *Note
  167.      Library flavors::).
  168.  
  169.      This option has no negative form.
  170.  
  171.    For more information, please refer to the `LibNIX' documentation.
  172.  
  173. 
  174. File: gcc-amigaos.info,  Node: -fbaserel,  Next: -resident,  Prev: -noixemul,  Up: Invocation
  175.  
  176. -fbaserel
  177. =========
  178.  
  179.    By default, the code generated by `GCC' references data using
  180. 32-bit, absolute addressing.
  181.  
  182.    The `-fbaserel' option will make `GCC' generate code that references
  183. data with 16 bit offsets relative to the `a4' address register. This
  184. makes executables smaller and faster. Unfortunately, the size of the
  185. data section cannot exceed 64 KB, so this option cannot be used for
  186. large programs, like `GCC' itself.
  187.  
  188.      *Note*: For a base-relative executable, `-fbaserel' needs to be
  189.      specified for compiling *and* linking. Base-relative programs
  190.      require special startup code and special versions of linker
  191.      libraries.  Since not all linker libraries are available in both
  192.      plain and base relative versions, the usefulness of this option is
  193.      limited. It is important to note that when the base-relative
  194.      library is missing, the linker will attempt to use the plain one.
  195.      This might result in strange link-time or even run-time errors.
  196.  
  197.      This option is the AmigaOS equivalent of the standard `GCC' option
  198.      `-fpic', which is not supported by the AmigaOS port.  `-fpic'
  199.      generates code that references data indirectly, through a "global
  200.      offset table". The special addressing modes available on the
  201.      `m68k' processor family allow for a much more efficient
  202.      implementation with `-fbaserel'.
  203.  
  204.      The negative form of `-fbaserel' is `-fno-baserel', and is on by
  205.      default.
  206.  
  207.    For more information, please refer to the `LibNIX' documentation.
  208.  
  209. 
  210. File: gcc-amigaos.info,  Node: -resident,  Next: -fbaserel32,  Prev: -fbaserel,  Up: Invocation
  211.  
  212. -resident
  213. =========
  214.  
  215.    Executables produced with the `-resident' option are "pure", so they
  216. can be made "resident" using the AmigaShell `resident' command.
  217. `resident' executables are loaded to memory just once, and several
  218. concurrent instances share the code section.
  219.  
  220.      *Note*: The compiler generates the same code for `-resident' as
  221.      for `-fbaserel' (*note -fbaserel::.). Only the linking stage is
  222.      different (special startup code is linked).
  223.  
  224.      This option has no negative form.
  225.  
  226.    For more information, please refer to the `LibNIX' documentation.
  227.  
  228. 
  229. File: gcc-amigaos.info,  Node: -fbaserel32,  Next: -resident32,  Prev: -resident,  Up: Invocation
  230.  
  231. -fbaserel32
  232. ===========
  233.  
  234.    The difference between the `-fbaserel32' and `-fbaserel' options
  235. (*note -fbaserel::.) is the same as between the standard `GCC' options
  236. `-fPIC' and `-fpic'.
  237.  
  238.    Code generated with `-fbaserel32' references data with 32 bit
  239. offsets relative to the `a4' address register. In contrast to the
  240. `-fbaserel' (*note -fbaserel::.) option, there is no 64 KB size limit.
  241. Unfortunately, the addressing modes with 32 bit offsets are only
  242. available on 68020 and higher processors. Therefore, it is necessary to
  243. specify `-m68020' or higher to use this option.
  244.  
  245.      *Note*: This option used to be called `-flarge-baserel' before
  246.      `Geek Gadgets' snapshot `970109'. Since it was not functional
  247.      then, this should not cause any compatibility problems.
  248.  
  249.      The negative form of `-fbaserel32' is `-fno-baserel32', and is on
  250.      by default.
  251.  
  252. 
  253. File: gcc-amigaos.info,  Node: -resident32,  Next: -msmall-code,  Prev: -fbaserel32,  Up: Invocation
  254.  
  255. -resident32
  256. ===========
  257.  
  258.    This option is an improved version of `-resident' (*note
  259. -resident::.) -- it does not impose any limits on data section size.
  260. Unfortunately, just like `-fbaserel32' (*note -fbaserel32::.), it is
  261. only available for 68020 or higher processors. Therefore, it is
  262. necessary to specify `-m68020' or higher to use this option.
  263.  
  264.      *Note*: This option was first made available in the `GCC' 2.7.2.1,
  265.      `Geek Gadgets' snapshot `970109'.
  266.  
  267.      This option has no negative form.
  268.  
  269. 
  270. File: gcc-amigaos.info,  Node: -msmall-code,  Next: -mstackcheck,  Prev: -resident32,  Up: Invocation
  271.  
  272. -msmall-code
  273. ============
  274.  
  275.    By default, the code generated by the compiler references functions
  276. using 32-bit, absolute addressing.
  277.  
  278.    Code generated by `GCC' with the `-msmall-code' option references
  279. symbols in the code section with 16 bit offsets, relative to the `PC'
  280. ("program counter"). This makes executables smaller and faster.
  281. Unfortunately, the size of the code section is generally limited to 32
  282. KB, so this option can only be used for relatively small programs.
  283.  
  284.      *Note*: Actually, the compiler always generates 32-bit code
  285.      references. If the assembler can calculate the offset between the
  286.      referencing instruction and the referenced symbol (in other words,
  287.      if the referenced symbol is in the same source file), it replaces
  288.      the 32-bit reference with the `PC'-relative one. External
  289.      references are left intact, unless `-msmall-code' is used, in
  290.      which case the assembler generates `PC'-relative references, and
  291.      the exact offsets are calculated by the linker.
  292.  
  293.      This option has no negative form.
  294.  
  295.    For more information, please refer to the `LibNIX' documentation.
  296.  
  297. 
  298. File: gcc-amigaos.info,  Node: -mstackcheck,  Next: -mstackextend,  Prev: -msmall-code,  Up: Invocation
  299.  
  300. -mstackcheck
  301. ============
  302.  
  303.    By default, the code generated by `GCC' does not check if there is
  304. enough stack available before performing stack-consuming operations.
  305. This is generally not necessary on `UN*X' systems, where the stack is
  306. extended automagically whenever needed.
  307.  
  308.    Unfortunately, the AmigaOS provides tasks with a static, fixed size
  309. stack.
  310.  
  311.    However, if a program is compiled with `-mstackcheck', it will check
  312. if there is enough stack available before performing any stack-hungry
  313. operations. If there is a danger of stack overflow, the program will
  314. abort and the user will be notified.
  315.  
  316.    Needless to say, stack checking increases the executable size and the
  317. execution time.
  318.  
  319.      *Note*: Stack checking cannot be used for functions that might be
  320.      called from outside your task. This includes interrupt handlers,
  321.      shared library functions, hooks etc. In such cases, you should
  322.      either avoid using `-mstackcheck' for files containing such
  323.      functions, or use `__attribute__((interrupt))' (*note
  324.      interrupt::.).
  325.  
  326.      It is safe to call a function that performs stack checking from one
  327.      that does not, and vice versa.
  328.  
  329.      The negative form of `-mstackcheck' is `-mno-stackcheck', and is
  330.      on by default.
  331.  
  332.      *Warning*: `-mno-stackcheck' used to be called `-mnostackcheck'
  333.      before `Geek Gadgets' snapshot `961012'.
  334.  
  335.    For more information, please refer to the `LibNIX' documentation.
  336.  
  337. 
  338. File: gcc-amigaos.info,  Node: -mstackextend,  Next: -mfixedstack,  Prev: -mstackcheck,  Up: Invocation
  339.  
  340. -mstackextend
  341. =============
  342.  
  343.    `-mstackextend' is very similar to `-mstackcheck' (*note
  344. -mstackcheck::.).
  345.  
  346.    The main difference is that when a program runs out of stack, it is
  347. not aborted, but a new stack area is allocated and the program
  348. continues to run.
  349.  
  350.      *Note*: Stack extension can slow programs down significantly. It
  351.      is advised that programs are written in such a way that they do not
  352.      require too much stack. This can generally be achieved by
  353.      explicitly allocating memory for large structures and arrays using
  354.      functions like `malloc()' or `AllocMem()', instead of creating
  355.      them as local variables. Another method is replacing recursion
  356.      with iteration.  In addition, it might be considered to use stack
  357.      extension only for selected, "dangerous" functions (*note
  358.      stackext::.), not for all functions in a given program.
  359.  
  360.      The negative form of `-mstackextend' is `-mno-stackextend', and is
  361.      on by default.
  362.  
  363.      *Warning*: `-mno-stackextend' used to be called `-mnostackextend'
  364.      before `Geek Gadgets' snapshot `961012'.
  365.  
  366.    For more information, please refer to the `LibNIX' documentation.
  367.  
  368. 
  369. File: gcc-amigaos.info,  Node: -mfixedstack,  Next: -mrestore-a4,  Prev: -mstackextend,  Up: Invocation
  370.  
  371. -mfixedstack
  372. ============
  373.  
  374.    This option makes `GCC' generate plain code, that does neither stack
  375. checking nor extension. Since this is the default, there is generally
  376. no need to use this option.
  377.  
  378.      *Note*: This option has no negative form.
  379.  
  380. 
  381. File: gcc-amigaos.info,  Node: -mrestore-a4,  Next: -malways-restore-a4,  Prev: -mfixedstack,  Up: Invocation
  382.  
  383. -mrestore-a4
  384. ============
  385.  
  386.    This option is used to create the `IXEmul' shared libraries (those
  387. `*.ixlibrary' files).
  388.  
  389.    It sets `a4' to the appropriate value in the prologues of all public
  390. functions (i.e., functions with external linkage). This is necessary if
  391. these functions are called from the code of application.
  392.  
  393.      *Note*: This option should not be used except for the creation of
  394.      an `IXEmul' shared library.
  395.  
  396.      This option was first made available in the `GCC' 2.7.2, `Geek
  397.      Gadgets' snapshot `960902'. It used to be called `-frestore-a4',
  398.      and was relabeled to its current name in the `GCC' 2.7.2.1, `Geek
  399.      Gadgets' snapshot `961012'.
  400.  
  401.      The negative form of `-mrestore-a4' is `-mno-restore-a4', and is
  402.      on by default.
  403.  
  404.    For more information, please refer to the `A2IXLibrary'
  405. documentation.
  406.  
  407. 
  408. File: gcc-amigaos.info,  Node: -malways-restore-a4,  Next: -mregparm,  Prev: -mrestore-a4,  Up: Invocation
  409.  
  410. -malways-restore-a4
  411. ===================
  412.  
  413.    This option is very similar to `-mrestore-a4' (*note
  414. -mrestore-a4::.).
  415.  
  416.    The only difference is that it sets `a4' in all functions, including
  417. private ones (i.e., functions with internal linkage, `static'). This is
  418. safer than `-mrestore-a4' (*note -mrestore-a4::.), but is also slower.
  419.  
  420.      *Note*: This option should not be used except for the creation of
  421.      an `IXEmul' shared library.
  422.  
  423.      This option was first made available in the `GCC' 2.7.2, `Geek
  424.      Gadgets' snapshot `960902'. It used to be called
  425.      `-falways-restore-a4', and was relabeled to its current name in
  426.      the `GCC' 2.7.2.1, `Geek Gadgets' snapshot `961012'.
  427.  
  428.      The negative form of `-malways-restore-a4' is
  429.      `-mno-always-restore-a4', and is on by default.
  430.  
  431.    For more information, please refer to the `A2IXLibrary'
  432. documentation.
  433.  
  434. 
  435. File: gcc-amigaos.info,  Node: -mregparm,  Next: -frepo,  Prev: -malways-restore-a4,  Up: Invocation
  436.  
  437. -mregparm
  438. =========
  439.  
  440.    On the `m68k' architecture, `GCC' passes function arguments on the
  441. stack by default.
  442.  
  443.    `-mregparm' allows for passing arguments in registers. This can be
  444. slightly faster than the standard method of passing arguments on the
  445. stack.
  446.  
  447.    The full syntax of this option is:
  448.  
  449. -mregparm[=<value>]
  450.  
  451.    `value' should be an integer ranging from 1 to 4. If no `value' is
  452. provided, 2 will be used.
  453.  
  454.    Four types of function arguments are recognized:
  455.  
  456. `Integer'
  457.      Integer numbers (this includes enumerations, small structures and
  458.      `bool' in `C++', but excludes `long long', which is too large).
  459.      They are passed in data registers, starting from `d0'.
  460.  
  461. `Pointer'
  462.      Pointers to objects or functions (this includes `C++' references
  463.      and the implicit `this' argument). They are passed in address
  464.      registers, starting from `a0'.
  465.  
  466. `Float'
  467.      Floating point numbers. If the floating point code generation is
  468.      enabled, they are passed in floating point registers, starting from
  469.      `fp0'. Otherwise, they are handled like the next type.
  470.  
  471. `Other'
  472.      All the other types of arguments, like large structures, pointers
  473.      to class methods in `C++', etc. They are always passed on the
  474.      stack.
  475.  
  476.    The value given for `-mregparm' indicates how many arguments of each
  477. of the above first three types should be passed in registers.
  478.  
  479.    Example: `GCC' is invoked with `-mregparm' (without any value, so 2
  480. will be used) to compile a source containing the function:
  481.  
  482.      void fun(int a, char *str, char b, int c);
  483.  
  484.    `a' and `b' will be passed in `d0' and `d1', respectively, `str'
  485. will be passed in `a0', and `c' will be passed on the stack.
  486.  
  487.      *Note*: To use this option properly, it is very important that all
  488.      sources are fully prototyped. There may be very serious problems
  489.      if they are not, since `GCC' will have to "guess" where to put
  490.      arguments, potentially making a wrong decission. Example:
  491.  
  492.           [in file1.c]
  493.           void f(void)
  494.           {
  495.              g(0); /* Call to a function with no prototype.  The argument
  496.                       will be put in d0, since it is an integer.  */
  497.           }
  498.           
  499.           [in file2.c]
  500.           void g(char *a) /* The argument is expected in a0, since it is
  501.                              a pointer.  */
  502.           {
  503.           }
  504.  
  505.      `-Wimplicit -Wstrict-prototypes' should be used to ensure that
  506.      there are no prototypes missing.
  507.  
  508.      In case of `stdargs' functions, such as `printf', all arguments
  509.      are passed on the stack.
  510.  
  511.      As of this writing, `-mregparm' is supported by neither `IXEmul'
  512.      nor `LibNIX', so its usefulness is very limited.
  513.  
  514.      This option was first made available in the `GCC' 2.7.2.1, `Geek
  515.      Gadgets' snapshot `961012'.
  516.  
  517.      The negative form of `-mregparm' is `-mno-regparm', and is on by
  518.      default.
  519.  
  520. 
  521. File: gcc-amigaos.info,  Node: -frepo,  Prev: -mregparm,  Up: Invocation
  522.  
  523. -frepo
  524. ======
  525.  
  526.    The AmigaOS port of `GCC' includes `C++' "Template Repository"
  527. patch, so-called `repo' patch.
  528.  
  529.    In order to activate it, please compile `C++' source files with
  530. `-frepo'. The compiler will not generate unnecessary `template' code,
  531. and will create `.rpo' files that contain information about `template'
  532. symbols used in each source file.  Afterwards, during linking stage, a
  533. special tool called `collect2' will make sure that every required
  534. instantiation of each `template' is linked into the executable,
  535. recompiling some source files if necessary.
  536.  
  537.      *Note*: This option was first made available in the `GCC' 2.7.2.1,
  538.      `Geek Gadgets' snapshot `970109'.
  539.  
  540.      This option is not specific to the AmigaOS port of `GCC',
  541.      nevertheless it is not fully supported in the baseline sources.
  542.  
  543.      This patch has been created in Cygnus Support, a company that is a
  544.      major contributor to the `GNU' project. It has not been integrated
  545.      into the baseline sources due to design disagreements.
  546.  
  547.      The negative form of `-frepo' is `-fno-repo', and is on by default.
  548.  
  549.    For more information, please refer to the `G++ FAQ'.
  550.  
  551. 
  552. File: gcc-amigaos.info,  Node: Attributes,  Next: Defines,  Prev: Invocation,  Up: Top
  553.  
  554. Attributes
  555. **********
  556.  
  557.    The following non-standard attributes are available in the AmigaOS
  558. port of `GCC':
  559.  
  560. * Menu:
  561.  
  562. Variable attributes:
  563. * chip::      Put object in `chip' memory.
  564.  
  565. Function attributes:
  566. * saveds::    Reload `a4'.
  567. * interrupt:: Do not mess with the stack.
  568. * stackext::  Generate stack extension.
  569. * regparm::   Pass arguments in registers.
  570. * stkparm::   Pass arguments on the stack.
  571.  
  572. 
  573. File: gcc-amigaos.info,  Node: chip,  Next: saveds,  Prev: Attributes,  Up: Attributes
  574.  
  575. chip
  576. ====
  577.  
  578.    Amiga hardware requires some data to be located in `chip' memory.
  579.  
  580.    Typically, if an initialized buffer is required (containing a picture
  581. bitmap, for example), a plain, statically initialized buffer is used,
  582. and the data is copied into a dynamically allocated `MEMF_CHIP' buffer.
  583.  
  584.    This is not necessary with the `chip' attribute. If this attribute
  585. is specified for an initialized, static variable, it will be allocated
  586. in `chip' memory automagically by the AmigaOS.
  587.  
  588.    A small example:
  589.  
  590.      UWORD __attribute__((chip)) bitmap1[] = { ... };
  591.  
  592.      *Note*: For compatibility with other AmigaOS `C' compilers, a
  593.      preprocessor symbol `__chip' is available, which expands to
  594.      `__attribute__((chip))' (*note Keyword macros::.).
  595.  
  596.      All the `chip' attribute does is specifying that data should go to
  597.      a section called `.datachip'. Therefore, the standard `GCC'
  598.      feature `__attribute__((section(".datachip")))' can be used
  599.      instead.
  600.  
  601.      This attribute was first made available in the `GCC' 2.7.2.1,
  602.      `Geek Gadgets' snapshot `970328'.
  603.  
  604.      For proper operation, this attribute requires a special version of
  605.      the assembler, which generates standard AmigaOS object files. This
  606.      version is not yet available in `Geek Gadgets' in binary form,
  607.      since support for this object files format is not yet complete.
  608.  
  609. 
  610. File: gcc-amigaos.info,  Node: saveds,  Next: interrupt,  Prev: chip,  Up: Attributes
  611.  
  612. saveds
  613. ======
  614.  
  615.    This attribute is ignored, unless base-relative data (*note
  616. -fbaserel::.) is compiled.
  617.  
  618.    To improve speed, programs compiled with the AmigaOS port of `GCC'
  619. set the `a4' register to the appropriate value only once, in the
  620. startup code. Code generated with the standard `GCC' option `-fpic', in
  621. contrast, sets the `a4' register in every function which references
  622. global data.
  623.  
  624.    This is only safe as long as all function calls are performed from
  625. within your own code. Things become "tricky" if callback functions,
  626. like the AmigaOS hooks, interrupt handlers etc. are used. If global
  627. data is referenced in such functions, `a4' has to be set properly.
  628.  
  629.    This is exactly what the `saveds' attribute does: it initializes
  630. `a4' in the function prologue, and restores it to its original value in
  631. the function epilogue.
  632.  
  633.      *Note*: For compatibility with other AmigaOS `C' compilers, a
  634.      preprocessor symbol `__saveds' is available, which expands to
  635.      `__attribute__((saveds))' (*note Keyword macros::.).
  636.  
  637.      Please do not use this attribute in pure executables (*note
  638.      -resident::., *note -resident32::.). This is because several
  639.      invocations of pure executables can run concurrently, each one
  640.      having its own data section, and there is no way to find out to
  641.      which of these sections should `a4' be set.
  642.  
  643.      The `saveds' attribute is not necessary in function declarations
  644.      (prototypes).
  645.  
  646.    This attribute was first made available in the `GCC' 2.7.2.1, `Geek
  647. Gadgets' snapshot `961012'.
  648.  
  649. 
  650. File: gcc-amigaos.info,  Node: interrupt,  Next: stackext,  Prev: saveds,  Up: Attributes
  651.  
  652. interrupt
  653. =========
  654.  
  655.    This attribute should be used for any kind of callback functions that
  656. can be called from outside your task. This includes interrupt handlers,
  657. shared library functions, etc.
  658.  
  659.    Most often, the `interrupt' attribute is only necessary if a program
  660. is compiled with stack checking or extension (*note -mstackcheck::.,
  661. *note -mstackextend::.). It will prevent the compiler from generating
  662. stack checking or extension code for the function it was specified for.
  663.  
  664.    Additionally, it will set `CC' ("condition codes register") in the
  665. function epilogue to return value, by performing `tstl d0'.
  666.  
  667.      *Note*: For compatibility with other AmigaOS `C' compilers, a
  668.      preprocessor symbol `__interrupt' is available, which expands to
  669.      `__attribute__((interrupt))' (*note Keyword macros::.).
  670.  
  671.      The `interrupt' attribute is mutually exclusive with the
  672.      `stackext' attribute (*note stackext::.).
  673.  
  674.      This attribute is not necessary in function declarations
  675.      (prototypes).
  676.  
  677.    This attribute was first made available in the `GCC' 2.7.2.1, `Geek
  678. Gadgets' snapshot `961012'.
  679.  
  680. 
  681. File: gcc-amigaos.info,  Node: stackext,  Next: regparm,  Prev: interrupt,  Up: Attributes
  682.  
  683. stackext
  684. ========
  685.  
  686.    This attribute makes `GCC' generate stack extension code for the
  687. function for which it was used (*note -mstackextend::.). This makes it
  688. possible to use stack extension selectively, only for the "dangerous"
  689. functions -- recursive functions, functions with large local variables,
  690. etc.
  691.  
  692.      *Note*: For compatibility with other AmigaOS `C' compilers, a
  693.      preprocessor symbol `__stackext' is available, which expands to
  694.      `__attribute__((stackext))' (*note Keyword macros::.).
  695.  
  696.      The `stackext' attribute is mutually exclusive with the
  697.      `interrupt' attribute (*note interrupt::.).
  698.  
  699.      This attribute is not necessary in function declarations
  700.      (prototypes).
  701.  
  702.    This attribute was first made available in the `GCC' 2.7.2.1, `Geek
  703. Gadgets' snapshot `961012'.
  704.  
  705. 
  706. File: gcc-amigaos.info,  Node: regparm,  Next: stkparm,  Prev: stackext,  Up: Attributes
  707.  
  708. regparm
  709. =======
  710.  
  711.    The `regparm' attribute, together with the `stkparm' attribute
  712. (*note stkparm::.), can be used to fine-tune the way arguments are
  713. passed. It makes `GCC' pass arguments in registers for the function for
  714. which it was used, regardless of whether the global `-mregparm' option
  715. was used or not (*note -mregparm::.).
  716.  
  717.    An optional integer argument ranging from 1 to 4 indicates how many
  718. arguments of each type should be passed in registers (*note
  719. -mregparm::.). The syntax is the following:
  720.  
  721.      void __attribute__((regparm(3))) fun(int a, char *str, char b, int c);
  722.  
  723.    This will make `GCC' pass `a', `b' and `c' in `d0', `d1' and `d2',
  724. respectively, and `str' in `a0'.
  725.  
  726.    If the argument is not provided, the value given for `-mregparm'
  727. will be used (or 2 if that option was not specified, *note
  728. -mregparm::.).
  729.  
  730.      *Note*: There is generally no need to use this attribute unless
  731.      files compiled with different calling conventions are linked
  732.      together.
  733.  
  734.      For compatibility with other AmigaOS `C' compilers, a preprocessor
  735.      symbol `__regargs' is available, which expands to
  736.      `__attribute__((regparm))' (*note Keyword macros::.).
  737.  
  738.      The `regparm' attribute is mutually exclusive with the `stkparm'
  739.      attribute (*note stkparm::.).
  740.  
  741.      This attribute is necessary both in function declarations
  742.      (prototypes) and definitions (function code).
  743.  
  744.    This attribute was first made available in the `GCC' 2.7.2.1, `Geek
  745. Gadgets' snapshot `961012'.
  746.  
  747. 
  748. File: gcc-amigaos.info,  Node: stkparm,  Prev: regparm,  Up: Attributes
  749.  
  750. stkparm
  751. =======
  752.  
  753.    The `stkparm' attribute, together with the `regparm' attribute
  754. (*note regparm::.), can be used to fine-tune the way arguments are
  755. passed. It makes `GCC' pass arguments on stack for the function for
  756. which it was used, regardless of whether the global `-mregparm' option
  757. was used or not (*note -mregparm::.).
  758.  
  759.      *Note*: There is generally no need to use this attribute unless
  760.      files compiled with different calling conventions are linked
  761.      together.
  762.  
  763.      For compatibility with other AmigaOS `C' compilers, a preprocessor
  764.      symbol `__stdargs' is available, which expands to
  765.      `__attribute__((stkparm))' (*note Keyword macros::.).
  766.  
  767.      The `stkparm' attribute is mutually exclusive with the `regparm'
  768.      attribute (*note regparm::.).
  769.  
  770.      This attribute is necessary both in function declarations
  771.      (prototypes) and definitions (function code).
  772.  
  773.    This attribute was first made available in the `GCC' 2.7.2.1, `Geek
  774. Gadgets' snapshot `961012'.
  775.  
  776. 
  777. File: gcc-amigaos.info,  Node: Defines,  Next: Miscellaneous,  Prev: Attributes,  Up: Top
  778.  
  779. Defines
  780. *******
  781.  
  782.    The AmigaOS-specific preprocessor symbols available in `GCC' can be
  783. divided into three groups:
  784.  
  785. * Menu:
  786.  
  787. * Identifying machine:: What machine is this?
  788. * Options information:: Which options have been specified?
  789. * Keyword macros::      Compatibility with other compilers.
  790.  
  791. 
  792. File: gcc-amigaos.info,  Node: Identifying machine,  Next: Options information,  Prev: Defines,  Up: Defines
  793.  
  794. Symbols identifying machine
  795. ===========================
  796.  
  797.    The following machine-identifying preprocessor symbols are available:
  798.  
  799. `mc68000'
  800.      This macro identifies the machine as having a CPU from the Motorola
  801.      68000 family.
  802.  
  803. `amiga'
  804.  
  805. `amigaos'
  806.  
  807. `amigados'
  808.      These macros identify the machine as being an Amiga, running the
  809.      AmigaOS.
  810.  
  811. `AMIGA'
  812.  
  813. `MCH_AMIGA'
  814.      These macros are provided for compatibility with other AmigaOS `C'
  815.      compilers.
  816.  
  817.      *Note*: These symbols are available in three groups: plain (as
  818.      specified above), with two leading underscores, and with two
  819.      leading and two tailing underscores. The plain ones are not
  820.      available when compiling with the `-ansi' option.
  821.  
  822.      The `amigados' symbol is obsolete and will be removed in future.
  823.      Please use `amigaos', which was first made available in the `GCC'
  824.      2.7.2.1, `Geek Gadgets' snapshot `961012'.
  825.  
  826. 
  827. File: gcc-amigaos.info,  Node: Options information,  Next: Keyword macros,  Prev: Identifying machine,  Up: Defines
  828.  
  829. Symbols identifying specified options
  830. =====================================
  831.  
  832.    `GCC' has several options to choose the CPU model that the code
  833. should be generated for. The following preprocessor symbols identify
  834. which options have been specified on the command line:
  835.  
  836. `mc68020'
  837.      Either one of `-m68020', `-mc68020' or `-mc68020-40' has been
  838.      specified.
  839.  
  840. `mc68030'
  841.      `-m68030' has been specified.
  842.  
  843. `mc68040'
  844.      `-m68040' has been specified.
  845.  
  846. `mc68060'
  847.      `-m68060' *[EXPERIMENTAL]* has been specified.
  848.  
  849. `__HAVE_68881__'
  850.      `-m68881' has been specified.
  851.  
  852.      *Note*: The symbols beginning with `mc' are available in three
  853.      groups: plain (as specified above), with two leading underscores,
  854.      and with two leading and two tailing underscores. The plain ones
  855.      are not available when compiling with the `-ansi' option. The
  856.      "underscored" ones were first made available in the `GCC' 2.7.2.1,
  857.      `Geek Gadgets' snapshot `970109'.
  858.  
  859.      `mc68000' is defined regardless of which `-m680x0' options have
  860.      been used.
  861.  
  862.    In addition to the above, a preprocessor symbol `ixemul' (together
  863. with the "underscored" versions) is available when not compiling with
  864. `-noixemul' (*note -noixemul::.) and identifies the runtime environment
  865. as `IXEmul'. This symbol was first made available in the `GCC' 2.7.2.1,
  866. `Geek Gadgets' snapshot `970328'.
  867.  
  868. 
  869. File: gcc-amigaos.info,  Node: Keyword macros,  Prev: Options information,  Up: Defines
  870.  
  871. "Keyword" macros
  872. ================
  873.  
  874.    Most AmigaOS-specific `C' compilers have special "custom keywords",
  875. which make the AmigaOS-specific development easier.  Unfortunately, the
  876. idea of "custom keywords" is not available in `GCC'. However,
  877. `attributes' are available, and they provide virtually identical
  878. functionality. For compatibility with other AmigaOS `C' compilers,
  879. preprocessor symbols are provided, which expand to the appropriate
  880. `attributes' (*note Attributes::.).
  881.  
  882. `__chip'
  883.      *Note chip::.
  884.  
  885. `__saveds'
  886.      *Note saveds::.
  887.  
  888. `__interrupt'
  889.      *Note interrupt::.
  890.  
  891. `__stackext'
  892.      *Note stackext::.
  893.  
  894. `__regargs'
  895.      *Note regparm::.
  896.  
  897. `__stdargs'
  898.      *Note stkparm::.
  899.  
  900. `__aligned'
  901.      This expands to the standard `GCC' `__attribute__((aligned(4)))'.
  902.  
  903.      *Note*: With `SAS/C', these keywords may be specified either
  904.      before or after the type, so the following declaration is correct:
  905.  
  906.           __saveds void func(void);
  907.  
  908.      Unfortunately, the syntax rules of `GCC' 2.7.2.1 do not allow to
  909.      specify the attributes before the type, so the above example must
  910.      be changed to:
  911.  
  912.           void __saveds func(void);
  913.  
  914.      This will be fixed in `GCC' 2.8.0.
  915.  
  916. 
  917. File: gcc-amigaos.info,  Node: Miscellaneous,  Next: Index,  Prev: Defines,  Up: Top
  918.  
  919. Miscellaneous
  920. *************
  921.  
  922.    The following "hard to categorize" features are available in the
  923. AmigaOS port of `GCC':
  924.  
  925. * Menu:
  926.  
  927. * Explicit register specification:: Specify registers for arguments.
  928. * Case sensitive CPP::              <String.h> is not the same as <string.h>
  929. * GCCPRIORITY::                     Set the priority of the compiler.
  930. * Library flavors::                 Linker libraries.
  931.  
  932. 
  933. File: gcc-amigaos.info,  Node: Explicit register specification,  Next: Case sensitive CPP,  Prev: Miscellaneous,  Up: Miscellaneous
  934.  
  935. Explicit register specification
  936. ===============================
  937.  
  938.    In certain situations, like writing callback hooks, "patchers",
  939. standard shared libraries, etc., functions have to receive arguments in
  940. particular registers.
  941.  
  942.    `-mregparm' (*note -mregparm::.) is not appropriate in this case,
  943. since it does not give the programmer enough control on *which*
  944. registers will be used.
  945.  
  946.    To overcome this problem in the AmigaOS port of `GCC', explicit
  947. register specification has been extended to be available for function
  948. arguments, as well:
  949.  
  950.      void myhook(struct Hook* hook __asm("a0"), APTR object __asm("a2"),
  951.                  APTR message __asm("a1"))
  952.      {
  953.          ...
  954.      }
  955.  
  956.      *Note*: This feature is currently not available in `G++'.
  957.  
  958.      Only the `ANSI'-style declarations (prototypes) are supported.
  959.  
  960.      Registers have to be specified both in function declarations
  961.      (prototypes) and definitions (function code).
  962.  
  963.    This feature was first made available in the `GCC' 2.7.2.1, `Geek
  964. Gadgets' snapshot `961012'.
  965.  
  966. 
  967. File: gcc-amigaos.info,  Node: Case sensitive CPP,  Next: GCCPRIORITY,  Prev: Explicit register specification,  Up: Miscellaneous
  968.  
  969. Case sensitive CPP
  970. ==================
  971.  
  972.    The preprocessor available in the AmigaOS port of `GCC' is case
  973. sensitive. This means, that the header names provided in the `#include'
  974. directives have to be correct, including upper and lower case letters.
  975. This affects only the way the preprocessor works.  Currently available
  976. native AmigaOS file systems are case insensitive.
  977.  
  978.      *Note*: This might seem like a horrible hack and a crazy attempt
  979.      to implement a "ridiculous" UNIX feature on Amiga. However, this
  980.      feature has been introduced to terminate the endless `G++'
  981.      problems with a standard `ANSI C' header `string.h': under the
  982.      AmigaOS, a `C++' header `String.h' would be included, instead.
  983.  
  984. 
  985. File: gcc-amigaos.info,  Node: GCCPRIORITY,  Next: Library flavors,  Prev: Case sensitive CPP,  Up: Miscellaneous
  986.  
  987. GCCPRIORITY
  988. ===========
  989.  
  990.    `GCC' supports one AmigaOS-specific environment variable:
  991. `GCCPRIORITY'.
  992.  
  993.    This variable specifies the `exec' priority of the compiler. If this
  994. variable is not set, the default Shell priority will be used.
  995.  
  996.      *Note*: By default, the AmigaOS assigns the priority `0' to user
  997.      tasks. It is thus generally unwise to set `GCCPRIORITY' higher
  998.      than `0'.
  999.  
  1000. 
  1001. File: gcc-amigaos.info,  Node: Library flavors,  Prev: GCCPRIORITY,  Up: Miscellaneous
  1002.  
  1003. Library flavors
  1004. ===============
  1005.  
  1006.    The AmigaOS port of `GCC' may use different linker libraries
  1007. depending upon the options used while invoking the compiler. These
  1008. libraries reside in subdirectories of the standard locations, such as
  1009. `GG:lib/' or, with `GCC' 2.7.2.1,
  1010. `GG:lib/gcc-lib/m68k-amigaos/2.7.2.1/'.
  1011.  
  1012.    If you invoke `gcc' with `-v', you'll see the precise flavor of
  1013. libraries used as a `-fl' option in the `ld' invocation.  Here is a
  1014. list of the available flavors (and hence the subdirectories names):
  1015.  
  1016.    * `libb' corresponds to the *Note -fbaserel::. option.
  1017.  
  1018.    * `libb32' corresponds to the *Note -fbaserel32::. option.
  1019.  
  1020.    * `libm020' corresponds to the `-m68020' (or higher) options.
  1021.  
  1022.    * `libm881' corresponds to the `-m68881' option.
  1023.  
  1024.    * `libnix' corresponds to the *Note -noixemul::. option.
  1025.  
  1026.    More than one flavor can be specified simultaneously. For example,
  1027. when both *Note -fbaserel::. and `-m68020' are specified, the libraries
  1028. will be searched in `libb/libm020' subdirectory (as well as in `libb'
  1029. subdirectory and in the standard location).
  1030.  
  1031. 
  1032. File: gcc-amigaos.info,  Node: Index,  Prev: Miscellaneous,  Up: Top
  1033.  
  1034. Index
  1035. *****
  1036.  
  1037. * Menu:
  1038.  
  1039. * -fbaserel:                             -fbaserel.
  1040. * -fbaserel32:                           -fbaserel32.
  1041. * -fpic:                                 -fbaserel.
  1042. * -frepo:                                -frepo.
  1043. * -malways-restore-a4:                   -malways-restore-a4.
  1044. * -mfixedstack:                          -mfixedstack.
  1045. * -mregparm:                             -mregparm.
  1046. * -mrestore-a4:                          -mrestore-a4.
  1047. * -msmall-code:                          -msmall-code.
  1048. * -mstackcheck:                          -mstackcheck.
  1049. * -mstackextend:                         -mstackextend.
  1050. * -noixemul:                             -noixemul.
  1051. * -resident:                             -resident.
  1052. * -resident32:                           -resident32.
  1053. * 32 KB code limit:                      -msmall-code.
  1054. * 64 KB data limit:                      -fbaserel.
  1055. * <String.h> is not the same as <string.h>: Case sensitive CPP.
  1056. * a4:                                    -fbaserel.
  1057. * Attributes:                            Attributes.
  1058. * Case sensitive CPP:                    Case sensitive CPP.
  1059. * chip:                                  chip.
  1060. * Command line options:                  Invocation.
  1061. * Compatibility with other compilers:    Keyword macros.
  1062. * Defines:                               Defines.
  1063. * Do not mess with the stack:            interrupt.
  1064. * Enable C++ Template Repository:        -frepo.
  1065. * Explicit register specification:       Explicit register specification.
  1066. * GCCPRIORITY:                           GCCPRIORITY.
  1067. * Generate stack extension:              stackext.
  1068. * interrupt:                             interrupt.
  1069. * Introduction:                          Introduction.
  1070. * Invocation:                            Invocation.
  1071. * IXEmul:                                -noixemul.
  1072. * Keyword macros:                        Keyword macros.
  1073. * LibNIX:                                -noixemul.
  1074. * Library flavors:                       Library flavors.
  1075. * Link with LibNIX:                      -noixemul.
  1076. * Linker libraries:                      Library flavors.
  1077. * Miscellaneous:                         Miscellaneous.
  1078. * Pass arguments in registers:           regparm.
  1079. * Pass arguments on the stack:           stkparm.
  1080. * Pass function arguments in registers:  -mregparm.
  1081. * Preprocessor symbols:                  Defines.
  1082. * Produce a pure executable:             -resident.
  1083. * Produce a pure executable with no size limits: -resident32.
  1084. * Produce a4-relative data:              -fbaserel.
  1085. * Produce a4-relative data with no size limits: -fbaserel32.
  1086. * Produce PC-relative code:              -msmall-code.
  1087. * Produce plain code:                    -mfixedstack.
  1088. * Produce stack-checking code:           -mstackcheck.
  1089. * Produce stack-extending code:          -mstackextend.
  1090. * Purpose of this document:              Introduction.
  1091. * Put object in chip memory:             chip.
  1092. * regparm:                               regparm.
  1093. * Reload a4:                             saveds.
  1094. * Reload a4 in all functions:            -malways-restore-a4.
  1095. * Reload a4 in public functions:         -mrestore-a4.
  1096. * saveds:                                saveds.
  1097. * Set the priority of the compiler:      GCCPRIORITY.
  1098. * Specify registers for arguments:       Explicit register specification.
  1099. * stackext:                              stackext.
  1100. * stkparm:                               stkparm.
  1101. * Symbols identifying CPU:               Options information.
  1102. * Symbols identifying ixemul:            Options information.
  1103. * Symbols identifying machine:           Identifying machine.
  1104. * Symbols identifying specified options: Options information.
  1105. * Uncategorizable:                       Miscellaneous.
  1106. * Variable and function attributes:      Attributes.
  1107. * What machine is this:                  Identifying machine.
  1108. * Which CPU model options have been specified: Options information.
  1109.  
  1110.  
  1111. 
  1112. Tag Table:
  1113. Node: Top423
  1114. Node: Introduction877
  1115. Node: Invocation3733
  1116. Node: -noixemul4853
  1117. Node: -fbaserel5929
  1118. Node: -resident7537
  1119. Node: -fbaserel328204
  1120. Node: -resident329165
  1121. Node: -msmall-code9770
  1122. Node: -mstackcheck10994
  1123. Node: -mstackextend12537
  1124. Node: -mfixedstack13796
  1125. Node: -mrestore-a414149
  1126. Node: -malways-restore-a415098
  1127. Node: -mregparm16075
  1128. Node: -frepo19041
  1129. Node: Attributes20265
  1130. Node: chip20755
  1131. Node: saveds22202
  1132. Node: interrupt23825
  1133. Node: stackext25022
  1134. Node: regparm25912
  1135. Node: stkparm27495
  1136. Node: Defines28557
  1137. Node: Identifying machine28941
  1138. Node: Options information29958
  1139. Node: Keyword macros31441
  1140. Node: Miscellaneous32716
  1141. Node: Explicit register specification33205
  1142. Node: Case sensitive CPP34373
  1143. Node: GCCPRIORITY35218
  1144. Node: Library flavors35726
  1145. Node: Index36888
  1146. 
  1147. End Tag Table
  1148.